package com.danicsoft.daide.serverclient;

import java.util.List;

import com.danicsoft.daide.command.OrderSpec;
import com.danicsoft.daide.command.Turn;
import com.danicsoft.daide.command.UnitPos;
import com.danicsoft.daide.token.StandardToken;

/**
 * This interface stands for a player. It includes all methods a server will
 * ever need to call to update a player its status.
 * 
 * @author Daniel Yule (daniel.yule@gmail.com)
 * @version 1.0
 */
public interface Player {

	/**
	 * Called when some units have not recived movement orders.
	 * 
	 * @param missingPositions
	 *        The positions that require orders still.
	 */
	public void notifyOfMissingOrders(List<UnitPos> missingPositions);

	/**
	 * Called whenever some units which have been disloged have not recieved
	 * retreat orders.
	 * 
	 * @param missingRetreats
	 *        The list of units which have not recieved retreat orders.
	 */
	public void notifyOfMissingRetreats(List<UnitPos> missingRetreats);

	/**
	 * Called whenever the player has lost or gained supply centres since the
	 * last build turn, and has not submitted build/remove/waive orders for the
	 * difference.
	 * 
	 * @param removalAmount
	 *        The amount of units that must be removed. If negative, the number
	 *        of builds.
	 */
	public void notifyOfMissingRemovals(int removalAmount);

	/**
	 * Accept order that has been sent. This does not mean it has been added. It
	 * has only been added if <code>note</code> is MBV (0x00)
	 * 
	 * @param order
	 *        The order that has been accepted
	 * @param note
	 *        The note that accompanies this order
	 */
	public void acceptOrder(OrderSpec order, byte note);

	/**
	 * Notifies the client that the next turn has begun.
	 * 
	 * @param turn
	 *        The turn that started.
	 */
	public void nextTurn(TurnInfo turn);

	/**
	 * Inform the player that we are starting the game.
	 * 
	 * @param playerPower
	 *        The power this player is to play.
	 * @param playerPasscode
	 *        The passcode to use on re-connect.
	 * @param info
	 * @param startingInfo
	 *        The turn information for the first turn. Does not contain any
	 *        order information.
	 */
	public void startGame(StandardToken playerPower, int playerPasscode, VariantInfo info, TurnInfo startingInfo);

	/**
	 * Inform the observer that we are starting the game.
	 * 
	 * @param startingTurn
	 *        The turn information for the first turn. Does not contain any
	 *        order information.
	 */
	public void startGame(TurnInfo startingTurn);

	/**
	 * Notifies the player that they have been accepted as either a new player,
	 * or a returning player from a broken connection.
	 */
	public void accept();

	/**
	 * Notfies the player that they have been rejected as part of this game,
	 * either because they tried to join a game already in progress, or because
	 * they attempted to rejoin a game and did not replace a power.
	 */
	public void reject();

	/**
	 * Get the power that this player is playing, if it has been assigned.
	 * 
	 * @return A StandardToken representing the power they are playing.
	 */
	public StandardToken getPower();

	/**
	 * Get the passcode for this player, if it has been assigned. If not is is
	 * 0.
	 * 
	 * @return The passcode for this player.
	 */
	public int getPasscode();

	/**
	 * Gets the name of the client.
	 * 
	 * @return The name of the client.
	 */
	public String getName();

	/**
	 * Gets the current state of the player.
	 * 
	 * @return The state of the player.
	 */
	public PLAYER_STATE getState();

	/**
	 * Gets the version of the client.
	 * 
	 * @return THe version of the client.
	 */
	public String getVersion();

	/**
	 * Inform the player that an admin message has been sent.
	 * 
	 * @param from
	 *        Who the message is from.
	 * @param message
	 *        The message that was sent
	 */
	public void adminMessage(String from, String message);

	/**
	 * Notify the player that a deadline is coming in <code>secondsLeft</code>
	 * seconds.
	 * 
	 * @param secondsLeft
	 *        The number of seconds until the deadline.
	 */
	public void notifyUpcomingDeadline(int secondsLeft);

	/**
	 * Notify the player that we have received all of the map information we
	 * need.
	 * 
	 * @param mInfo
	 *        The map information we have received.
	 */
	public void notifyMapInfo(MapInfo mInfo);
	
	/**
	 * Notify the player that the game has ended.
	 * @param winners The winner, or if there was a draw, winners of this game
	 * @param turn The year the game was won in.
	 */
	public void endGame(List<StandardToken> winners, Turn turn);

}
